src/commands/convert.test.ts (1)

53-112: Add regression cases for missing Linear option values.

Current tests don’t lock behaviour for --team/--project/--parent when the value is omitted and the next token is another flag. That edge case is where parsing currently degrades.

Suggested tests

   describe('Linear-specific options', () => {
+    test('rejects --team without a value', () => {
+      const result = parseConvertArgs([
+        '--to', 'linear',
+        '--team', '--project', 'Sprint 1',
+        'input.md',
+      ]);
+      expect(result).toBeNull();
+    });
+
+    test('rejects --project without a value', () => {
+      const result = parseConvertArgs([
+        '--to', 'linear',
+        '--team', 'ENG',
+        '--project', '--parent', 'ENG-1',
+        'input.md',
+      ]);
+      expect(result).toBeNull();
+    });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/commands/convert.test.ts` around lines 53 - 112, Add regression tests
around parseConvertArgs to assert it fails (returns null or validation error)
when Linear-specific flags are provided without values or the next token is
another flag: add cases for '--team' with missing value (e.g.
['--to','linear','--team','--project','input.md']), '--project' missing value
(e.g. ['--to','linear','--project','--team','input.md']), and '--parent' missing
value (including when the next token looks like a flag or starts with '-');
ensure each new test calls parseConvertArgs and expects null, and include both
the linear-required check and non-linear behavior where appropriate to lock the
parser behavior.

src/commands/convert.ts (1)

700-705: Add a defensive guard for args.team in the exported Linear executor.

Line 704 uses a non-null assertion. Because executeLinearConversion is exported, direct callers can bypass parseConvertArgs and hit avoidable runtime errors.

Proposed fix

 export async function executeLinearConversion(
   parsed: import('../prd/parser.js').ParsedPrd,
   args: ConvertArgs
 ): Promise<void> {
-  const teamKey = args.team!;
+  if (!args.team) {
+    printError('Error: --team <team-key> is required for Linear conversion');
+    process.exit(1);
+  }
+  const teamKey = args.team;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/commands/convert.ts` around lines 700 - 705, The exported function
executeLinearConversion uses a non-null assertion on args.team (teamKey =
args.team!) which can cause runtime errors if callers bypass parseConvertArgs;
add a defensive guard at the start of executeLinearConversion to validate
args.team (e.g., check if falsy) and handle the case by throwing a clear Error
or returning early with a logged message; update any error text to reference
executeLinearConversion and the team argument so callers get a descriptive
failure rather than a crash.

src/plugins/trackers/builtin/linear/client.test.ts (1)

339-363: Make the pagination mock cursor-sensitive.

The second page is returned purely on call count, so this still passes if getChildIssues() accidentally re-requests page 1 and never forwards the previous cursor. Having the mock assert the follow-up cursor would turn this into a real pagination regression test.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/plugins/trackers/builtin/linear/client.test.ts` around lines 339 - 363,
The pagination mock for mockSdkResponses.issue.children is currently based only
on call count, which won't catch regressions where getChildIssues incorrectly
re-requests the first page; update the mock to be cursor-sensitive by inspecting
the incoming cursor argument and returning the first-page response only when
cursor is undefined/null and the second-page response only when cursor ===
'cursor-1' (matching pageInfo.endCursor), and add an assertion inside the mock
to fail if an unexpected cursor is passed; this targets the mock used in the
test for getChildIssues and ensures pageInfo.endCursor and subsequent calls are
validated.

src/plugins/trackers/builtin/linear/index.ts (2)

463-472: Workflow states cache may become stale if team changes within the same plugin instance.

The cache invalidation at line 464 checks this.teamId === teamId, but this.teamId is updated after fetching new states (line 469). This means:

1. First call with team A: cache miss → fetch → set this.teamId = A
2. Second call with team B: condition this.teamId === teamId is false (A !== B) → fetch → set this.teamId = B
3. Third call with team A: condition is false (B !== A) → unnecessary refetch

While functionally correct (no stale data served), there's a minor inefficiency. Consider caching per team ID using a Map instead if multiple teams are expected.

💡 Optional: Per-team caching

-  /** Cache of workflow states per team to avoid repeated API calls. */
-  private workflowStatesCache: WorkflowStateSummary[] | null = null;
+  /** Cache of workflow states per team to avoid repeated API calls. */
+  private workflowStatesCache = new Map<string, WorkflowStateSummary[]>();

   private async getWorkflowStates(teamId: string): Promise<WorkflowStateSummary[]> {
-    if (this.workflowStatesCache && this.teamId === teamId) {
-      return this.workflowStatesCache;
+    const cached = this.workflowStatesCache.get(teamId);
+    if (cached) {
+      return cached;
     }

     const states = await this.client.getWorkflowStates(teamId);
-    this.teamId = teamId;
-    this.workflowStatesCache = states;
+    this.workflowStatesCache.set(teamId, states);
     return states;
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/plugins/trackers/builtin/linear/index.ts` around lines 463 - 472, The
current getWorkflowStates method uses a single this.workflowStatesCache and
this.teamId, causing unnecessary refetches when the plugin serves multiple
teams; replace the single cache with a per-team Map (e.g., workflowStatesCache:
Map<string, WorkflowStateSummary[]>) and update getWorkflowStates to check
workflowStatesCache.get(teamId) before calling
this.client.getWorkflowStates(teamId), and then store the fetched states with
workflowStatesCache.set(teamId, states); adjust any usages of
this.workflowStatesCache and remove or repurpose the single this.teamId field
accordingly so caching is keyed by teamId.

---

149-149: Consider adding a defensive guard before using client in public methods.

The definite assignment assertion (!) assumes client is always initialised before use. While initialize() sets ready = false on failure, the public methods (getTasks, getTask, etc.) don't check isReady() before accessing this.client.

If a caller invokes these methods without checking isReady() first, they'll encounter a runtime error on the uninitialised client.

🛡️ Optional defensive guard pattern

 override async getTasks(filter?: TaskFilter): Promise<TrackerTask[]> {
+  if (!this.ready) {
+    return [];
+  }
   const parentId = filter?.parentId ?? this.epicId;

Or centralise the check in a helper:

private ensureReady(): void {
  if (!this.ready) {
    throw new Error('LinearTrackerPlugin is not initialised');
  }
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/plugins/trackers/builtin/linear/index.ts` at line 149, Public methods
like getTasks and getTask access the definite-assigned field client which may be
uninitialised if initialize() failed; add a defensive guard before any use of
this.client by either (A) introducing a private ensureReady() that throws if
!this.ready and calling ensureReady() at the start of every public method
(getTasks, getTask, etc.), or (B) make client possibly undefined and check if
(this.client == null) { throw new Error('LinearTrackerPlugin is not
initialised'); } in those methods; reference the existing ready flag and
initialize() to keep semantics consistent.

src/commands/convert.ts (1)

718-724: Clarify partial success behaviour in return value.

The function returns success: true if any child issues were created (childIssues.length > 0), even if some failed. This is reasonable for a conversion tool, but the calling code at lines 840-843 exits with an error message "No child issues were created. Conversion failed." which only triggers on complete failure.

Consider documenting this partial success behaviour or adding a warning when some stories failed to create.

💡 Optional: Add partial success warning

   if (!result.success) {
     printError('No child issues were created. Conversion failed.');
     process.exit(1);
   }
+
+  if (result.childIssues.length < parsed.userStories.length) {
+    printInfo(`Warning: Only ${result.childIssues.length} of ${parsed.userStories.length} stories were created.`);
+  }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/commands/convert.ts` around lines 718 - 724, The current return sets
success: childIssues.length > 0 which treats any partial creation as full
success; change this to explicitly represent partial success by either (A) make
success true only when all expected child issues were created (e.g. success =
childIssues.length === expectedChildrenCount) and add a new field like partial =
childIssues.length > 0 && childIssues.length < expectedChildrenCount, or (B)
keep success as-is but add a warning flag/message when childIssues.length > 0 &&
childIssues.length < expectedChildrenCount so the caller can log a warning;
reference the return object containing success, parentIssue, childIssues,
relationsCreated and use whatever variable holds the expected count of children
(e.g., the original stories/children array) to compute full vs partial success.

src/plugins/trackers/builtin/linear/index.ts (1)

482-485: Consider whether cancelled tasks should count as completed.

The countCompletedChildren method includes both 'completed' and 'canceled' states in the count. Whilst this is reasonable for progress tracking (both represent "resolved" work), it may be surprising if users expect completedCount to exclude cancelled items.

This is a minor semantic consideration and may well be intentional for your use case.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/plugins/trackers/builtin/linear/index.ts` around lines 482 - 485, The
countCompletedChildren method currently treats both 'completed' and 'canceled'
Issue.state types as completed; decide the intended semantics and update the
implementation accordingly: if cancelled tasks should not count toward
completedCount, change the filter in countCompletedChildren to only include
s?.type === 'completed'; if the current behavior is intentional, add a brief
clarifying comment above countCompletedChildren explaining that 'canceled' is
considered equivalent to 'completed' for progress metrics (or make this behavior
configurable via a flag/option passed to the function).